Population options

The following chapter contains all Population code options, along with their descriptions.

Public options

In this section we list the public options for the population code. These are meant to be changed by the user.

Public options

Option

Description

C_auto_logging

Description:

Dictionary containing parameters to be logged by binary_c. The structure of this dictionary is as follows: the key is used as the headline which the user can then catch. The value at that key is a list of binary_c system parameters (like star[0].mass).

Default value:

None

Validation:

<class ‘dict’>

C_logging_code

Description:

Variable to store the exact code that is used for the custom_logging. In this way the user can do more complex logging, as well as putting these logging strings in files.

Default value:

None

Validation:

<class ‘str’>

HPC_force_join

Description:

Flag to enforce the joining of the results and skip checking our own job. Only used when HPC variable (“slurm” or “condor”) is 3.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

HPC_rebuild_joinlist

Description:

Flag to ignore the joinlist we would usually use and rebuild it automatically.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

Moe2017_options

Description:

Set of options for the Moe & diStefano initial distribution interpolation table functionality.

Default value:

None

Validation:

<class ‘dict’>

cache_dir

Description:

Directory where the chacheing files are stored.

Default value:

example path

Validation:

<class ‘str’>

combine_ensemble_with_thread_joining

Description:

Boolean flag on whether to combine everything and return it to the user or if false: write it to data_dir/ensemble_output_{population_id}_{thread_id}.json.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

command_line

Description:

Place where the extra command line arguments are stored in.

Default value:

example path

Validation:

<class ‘str’>

condor

Description:

Flag to enable running HTCondor (referred to as Condor here) jobs. Default is 0 which means no Condor. 1 means launch Condor jobs. Do not manually set this to 2 (run Condor jobs) or 3 (join Condor job data) unless you know what you are doing, this is usually done for you.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_ClusterID

Description:

Condor ClusterID variable, equivalent to Slurm’s jobid. Jobs are numbered <ClusterID>.<Process>.

Default value:

None

condor_Process

Description:

Condor Process variable, equivalent to Slurm’s jobarrayindex. Jobs are numbered <ClusterID>.<Process>.

Default value:

None

condor_bash

Description:

Points the location of the “bash” command, e.g. /bin/bash, that is used in Condor launch scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/bash

Validation:

<class ‘str’>

condor_batchname

Description:

Condor batchname option: this is what appears in condor_q.

Default value:

binary_c-condor

Validation:

<class ‘str’>

condor_date

Description:

Points the location of the “date” command, e.g. /usr/bin/date, that is used in Condor launch scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/date

Validation:

<class ‘str’>

condor_dir

Description:

Working directory containing e.g. scripts, output, logs (e.g. should be NFS available to all jobs). This directory should not exist when you launch the Condor jobs.

Default value:

Validation:

<class ‘str’>

condor_env

Description:

Points the location of the “env” command, e.g. /usr/bin/env or /bin/env, that is used in Condor launch scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/env

Validation:

<class ‘str’>

condor_extra_settings

Description:

Place to put extra configuration for the CONDOR submit file. The key and value of the dict will become the key and value of the line in te slurm batch file. Will be put in after all the other settings (and before the command). Take care not to overwrite something without really meaning to do so.

Default value:

{}

Validation:

<class ‘dict’>

condor_getenv

Description:

Flag to copy and use the environment at submission. You almost certainly want this to be True.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_initial_dir

Description:

Directory from which condor scripts are run. If set to the default, None, this is the directory from which your script is run.

Default value:

None

Validation:

<class ‘str’>

condor_kill_sig

Description:

Signal Condor should use to stop a process. Note that grid.py expects this to be “SIGINT” which is the default.

Default value:

SIGINT

Validation:

<class ‘str’>

condor_memory

Description:

In MB, the memory use (ImageSize) of the job.

Default value:

512

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

condor_njobs

Description:

Number of jobs that Condor will run.

Default value:

0

Validation:

<class ‘int’>

condor_postpone_join

Description:

Use to delay the joining of Condor grid data. If 1, data is not joined, e.g. if you want to do it off the condor grid (e.g. with more RAM). Default 0.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_postpone_submit

Description:

Debugging tool. If 1, the condor script is not submitted (useful for debugging). Default 0.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_pwd

Description:

Points the location of the “pwd” command, e.g. /bin/pwd, that is used in Condor launch scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/pwd

Validation:

<class ‘str’>

condor_q

Description:

The Condor_q command, usually “/usr/bin/condor_q” but will depend on your HTCondor installation.

Default value:

None

Validation:

<class ‘str’>

condor_requirements

Description:

Condor job requirements. These are passed to Condor directly, you should read the HTCondor manual to learn about this. If no requirements exist, leave as an string.

Default value:

Validation:

<class ‘str’>

condor_should_transfer_files

Description:

Condor’s option to transfer files at the end of the job. You should set this to “YES”.

Default value:

YES

Validation:

<class ‘str’>

condor_snapshot_on_kill

Description:

If 1 we save a snapshot on SIGKILL before exit.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_stream_error

Description:

Flag to activate Condor’s stderr stream. If False, this data is copied at the end of the job.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_stream_output

Description:

Flag to activate Condor’s stdout stream. If False, this data is copied at the end of the job.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

condor_submit

Description:

The Condor_submit command, usually “/usr/bin/condor_submit” but will depend on your HTCondor installation.

Default value:

None

Validation:

<class ‘str’>

condor_universe

Description:

The HTCondor “universe”: this is “vanilla” by default.

Default value:

vanilla

Validation:

<class ‘str’>

condor_warn_max_memory

Description:

In MB, the memory use (ImageSize) of the job.

Default value:

1024

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

condor_when_to_transfer_output

Description:

Condor’s option to decide when output files are transferred. You should usually set this to “ON_EXIT_OR_EVICT”.

Default value:

ON_EXIT_OR_EVICT

Validation:

<class ‘str’>

custom_generator

Description:

Custom system generator. The user can provide a custom system generator that generates the systems that will be evolved. This has to be of an iterable type, like list or generator.

Default value:

None

Validation:

<function iterator_validation at 0x7f7a7cfefdc0>

custom_logging_func_memaddr

Description:

Memory address where the custom_logging_function is stored.

Default value:

-1

Validation:

Any(<class ‘int’>, <function capsule_validation at 0x7f7a7cfefd30>, msg=None)

do_analytics

Description:

Flag whether to calculate some details about the performance of the population evolution.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

do_dry_run

Description:

Whether to do a dry run to calculate the total probability for this run.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

dry_run_hook

Description:

Function hook to be called for every system in a dry run. The function is passed a dict of the system parameters. Does nothing if None (the default).

Default value:

None

Validation:

<function callable_validation at 0x7f7a7d0a9dc0>

dry_run_num_cores

Description:

Number of parallel processes for the dry run (outer loop).

Default value:

1

Validation:

<class ‘int’>

email_notification_extra_info_function_hook

Description:

Function hook to allow extra information to be sent with the emails. This function currently can only accept the population_object parameter, which gives the user access to the population object that sends the email. This function should return a string that contains the additional information.

Default value:

None

Validation:

<function callable_validation at 0x7f7a7d0a9dc0>

email_notifications_APP_password

Description:

App password for the email notifications. On default the content of the “BCP_EMAIL_NOTIFICATION_APP_PW” environment variable is used.

Default value:

Validation:

<class ‘str’>

email_notifications_corresponding_email

Description:

Corresponding email address for the email notifications. Note that this has to be a gmail-based account with app-password authentication enabled. The content of “email_notifications_APP_password” will be used to authenticate.

Default value:

Validation:

<class ‘str’>

email_notifications_enabled

Description:

Flag to enable or disable email notifications about the outcome of the population evolution. This currently only works for gmail, and on an account that has the application specific password authentication enabled. See https://support.google.com/accounts/answer/185833?hl=en.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

email_notifications_recipients

Description:

List of recipients for the email notifications. The email will also be sent to the corresponding email, regardless of the recipients.

Default value:

[]

Validation:

[<class ‘str’>]

ensemble_factor_in_probability_weighted_mass

Description:

Flag to multiply all the ensemble results with 1/probability_weighted_mass.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

event_based_logging_combine_individual_event_files

Description:

Flag to enable enable combining the process-specific event output files into a single file. See “event_based_logging_combined_events_filename”.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

event_based_logging_combined_events_filename

Description:

Filename for the combined events file. See “event_based_logging_combine_individual_event_files”.

Default value:

all_events.dat

Validation:

<class ‘str’>

event_based_logging_handle_output

Description:

Flag to enable the processing of the event-based logging output from binary_c.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

event_based_logging_output_directory

Description:

Path to output directory for the event logs.

Default value:

None

Validation:

<class ‘str’>

event_based_logging_output_parser

Description:

Function that handles the processing of the event-based logging output. Note: this function needs to have the following arguments: self, events_parameters_list_dict, data_dir, output, separator.

Default value:

<function event_based_logging_output_parser at 0x7f7a841ed5e0>

Validation:

<function callable_validation at 0x7f7a7d0a9dc0>

event_based_logging_output_separator

Description:

Separator used during the processing of the event output.

Default value:

Validation:

<class ‘str’>

event_based_logging_parameter_list_dict

Description:

Dictionary that contains the lists of parameters per event type. Looks like {“<event type>”: [<event parameter list>}.

Default value:

{‘SN_BINARY’: [‘uuid’, ‘probability’, ‘event_number’, ‘event_type’, ‘zams_mass_1’, ‘zams_mass_2’, ‘zams_orbital_period’, ‘zams_separation’, ‘zams_eccentricity’, ‘time’, ‘metallicity’, ‘random_seed’, ‘SN_post_SN_mass’, ‘SN_post_SN_stellar_type’, ‘SN_type’, ‘SN_fallback_fraction’, ‘SN_fallback_mass’, ‘SN_post_SN_ecc’, ‘SN_post_SN_orbital_period’, ‘SN_post_SN_separation’, ‘SN_pre_SN_mass’, ‘SN_pre_SN_stellar_type’, ‘SN_pre_SN_radius’, ‘SN_pre_SN_core_mass’, ‘SN_pre_SN_CO_core_mass’, ‘SN_pre_SN_He_core_mass’, ‘SN_pre_SN_fraction_omega_crit’, ‘SN_pre_SN_ecc’, ‘SN_pre_SN_orbital_period’, ‘SN_pre_SN_separation’, ‘SN_pre_SN_companion_mass’, ‘SN_pre_SN_companion_radius’, ‘SN_pre_SN_companion_stellar_type’, ‘SN_starnum’, ‘SN_counter’, ‘SN_kick_v’, ‘SN_kick_omega’, ‘SN_kick_phi’], ‘SN_SINGLE’: [‘uuid’, ‘probability’, ‘event_number’, ‘event_type’, ‘zams_mass_1’, ‘time’, ‘metallicity’, ‘random_seed’, ‘SN_post_SN_mass’, ‘SN_post_SN_stellar_type’, ‘SN_type’, ‘SN_fallback_fraction’, ‘SN_fallback_mass’, ‘SN_pre_SN_mass’, ‘SN_pre_SN_stellar_type’, ‘SN_pre_SN_radius’, ‘SN_pre_SN_core_mass’, ‘SN_pre_SN_CO_core_mass’, ‘SN_pre_SN_He_core_mass’, ‘SN_pre_SN_fraction_omega_crit’, ‘SN_starnum’, ‘SN_counter’, ‘SN_kick_v’, ‘SN_kick_omega’, ‘SN_kick_phi’], ‘RLOF’: [‘uuid’, ‘probability’, ‘event_number’, ‘event_type’, ‘zams_mass_1’, ‘zams_mass_2’, ‘zams_orbital_period’, ‘zams_separation’, ‘zams_eccentricity’, ‘time’, ‘metallicity’, ‘random_seed’, ‘RLOF_initial_mass_accretor’, ‘RLOF_initial_mass_donor’, ‘RLOF_initial_radius_accretor’, ‘RLOF_initial_radius_donor’, ‘RLOF_initial_separation’, ‘RLOF_initial_orbital_period’, ‘RLOF_initial_stellar_type_accretor’, ‘RLOF_initial_stellar_type_donor’, ‘RLOF_initial_orbital_angular_momentum’, ‘RLOF_initial_stability’, ‘RLOF_initial_starnum_accretor’, ‘RLOF_initial_starnum_donor’, ‘RLOF_initial_time’, ‘RLOF_initial_disk’, ‘RLOF_final_mass_accretor’, ‘RLOF_final_mass_donor’, ‘RLOF_final_radius_accretor’, ‘RLOF_final_radius_donor’, ‘RLOF_final_separation’, ‘RLOF_final_orbital_period’, ‘RLOF_final_stellar_type_accretor’, ‘RLOF_final_stellar_type_donor’, ‘RLOF_final_orbital_angular_momentum’, ‘RLOF_final_stability’, ‘RLOF_final_starnum_accretor’, ‘RLOF_final_starnum_donor’, ‘RLOF_final_time’, ‘RLOF_final_disk’, ‘RLOF_total_mass_lost’, ‘RLOF_total_mass_accreted’, ‘RLOF_total_mass_transferred’, ‘RLOF_total_mass_lost_from_accretor’, ‘RLOF_total_mass_lost_from_common_envelope’, ‘RLOF_total_time_spent_masstransfer’, ‘RLOF_episode_number’], ‘DCO_formation’: [‘uuid’, ‘probability’, ‘event_number’, ‘event_type’, ‘zams_mass_1’, ‘zams_mass_2’, ‘zams_orbital_period’, ‘zams_separation’, ‘zams_eccentricity’, ‘time’, ‘metallicity’, ‘random_seed’, ‘DCO_stellar_type_1’, ‘DCO_stellar_type_2’, ‘DCO_mass_1’, ‘DCO_mass_2’, ‘DCO_separation’, ‘DCO_eccentricity’, ‘DCO_period’, ‘DCO_previous_separation’, ‘DCO_previous_eccentricity’, ‘DCO_previous_period’, ‘DCO_formation_time_in_years’, ‘DCO_inspiral_time_in_years’, ‘DCO_merger_time_in_years’, ‘DCO_total_rlof_episodes’, ‘DCO_stable_rlof_episodes’, ‘DCO_unstable_rlof_episodes’]}

Validation:

<class ‘dict’>

event_based_logging_remove_individual_event_files_after_combining

Description:

Flag to enable the removal of the process-specific event files after combining into one file.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

event_based_logging_remove_original_combined_events_file_after_splitting

Description:

Flag to enable the removal of the combined events file after splitting into event-specific files. See “event_based_logging_split_events_file_to_each_type”.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

event_based_logging_split_events_file_to_each_type

Description:

Flag to enable splitting the combined event file into event-specific files like RLOF_events, SN_events etc. See “event_based_logging_combine_individual_event_files”.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

evolution_type

Description:

Variable containing the type of evolution used of the grid. Multiprocessing, linear processing or possibly something else (e.g. for Slurm or Condor).

Default value:

grid

Validation:

All(<class ‘str’>, In([‘grid’, ‘monte_carlo’, ‘custom_generator’, ‘source_file’]), msg=None)

exit_after_dry_run

Description:

If True, exits after a dry run. Default is False.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

exit_code

Description:

Exit code of the population.

Default value:

0

Validation:

<class ‘int’>

failed_systems_threshold

Description:

Variable storing the maximum number of systems that are allowed to fail before logging their command line arguments to failed_systems log files.

Default value:

20

Validation:

<class ‘int’>

function_cache

Description:

If True, we use a cache for certain function calls.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

function_cache_TTL

Description:

Time-to-live for the cacheing.

Default value:

30

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

function_cache_default_maxsize

Description:

The default maxsize of the cache. Should be a power of 2.

Default value:

256

Validation:

<class ‘int’>

function_cache_default_type

Description:

One of the following types: LRUCache, LFUCache, FIFOCache, MRUCache, RRCache, TTLCache, NullCache, NoCache. You can find details of what these mean in the Python cachetools manual, except fo NoCache which means no cache is used at all, and NullCache is a dummy cache that never matches, used for testing overheads.

Default value:

NullCache

Validation:

<class ‘str’>

function_cache_functions

Description:

Functions that are included int he function-caching, including a configuration for the caching.

Default value:

{‘distribution_functions.powerlaw_constant’: (0, ‘NoCache’, ‘1,100,-2’), ‘distribution_functions.calculate_constants_three_part_powerlaw’: (16, ‘FIFOCache’, ‘0.1,0.5,1,100,-1.3,-2.3,-2.3’), ‘distribution_functions.gaussian_normalizing_const’: (16, ‘FIFOCache’, ‘1.0,1.0,-10.0,+10.0’), ‘spacing_functions.const_linear’: (16, ‘FIFOCache’, ‘1,10,9’), ‘spacing_functions.const_int’: (0, None, ‘1,10,9’), ‘spacing_functions.const_ranges’: (16, ‘FIFOCache’, ‘((0.1,0.65,10),(0.65,0.85,20),(0.85,10.0,10))’), ‘spacing_functions.gaussian_zoom’: (16, ‘FIFOCache’, ‘1.0,10.0,5.0,2.0,0.9,100’)}

Validation:

<class ‘dict’>

gridcode_filename

Description:

Filename for the grid code. Set and used by the population object. TODO: allow the user to provide their own function, rather than only a generated function.

Default value:

None

Validation:

<class ‘str’>

joinlist

Description:

Files that are to be joined by the HPC.

Default value:

None

Validation:

<class ‘list’>

log_args

Description:

Boolean to log the arguments.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

log_args_dir

Description:

Directory to log the arguments to.

Default value:

/tmp/binary_c_python-david/log_args

Validation:

<class ‘str’>

log_config_file

Description:

Configuration file file the logging module.

Default value:

None

Validation:

<function str_or_none_validation at 0x7f7a7d0a9ca0>

log_dt

Description:

Time between verbose logging output.

Default value:

5

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

log_failed_systems

Description:

Flag to enable logging of failed systems.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

log_failed_systems_dir

Description:

Directory the failed system information is logged to.

Default value:

/tmp/binary_c_python-david/failed_systems

Validation:

<class ‘str’>

log_file

Description:

Log file for the population object.

Default value:

/tmp/binary_c_python-david/population.log

Validation:

<class ‘str’>

log_newline

Description:

Newline character used at the end of verbose logging statements. This is n (newline) by default, but x0d (carriage return) might also be what you want.

Default value:

Validation:

<class ‘str’>

log_runtime_systems

Description:

Whether to log the runtime of the systems . Each systems run by the thread is logged to a file and is stored in the tmp_dir. (1 file per thread). Don’t use this if you are planning to run a lot of systems. This is mostly for debugging and finding systems that take long to run. Integer, default = 0. if value is 1 then the systems are logged.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

max_queue_size

Description:

Maximum size of the queue that is used to feed the processes. Don’t make this too big!.

Default value:

1000

Validation:

<class ‘int’>

modulo

Description:

The modulus of the population evolution. This is used if a population is evolved through several different machines.

Default value:

1

Validation:

<class ‘int’>

monte_carlo_count_threshold

Description:

Monte-Carlo system count threshold.

Default value:

-1

Validation:

<class ‘int’>

monte_carlo_custom_threshold_function

Description:

Custom threshold function for the monte-carlo sampling. This function needs to accept the arguments (self, result_queue).

Default value:

None

Validation:

<function callable_validation at 0x7f7a7d0a9dc0>

monte_carlo_mass_threshold

Description:

Monte-Carlo mass threshold.

Default value:

-1

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

monte_carlo_use_pre_calculated_distributions

Description:

Flag whether to pre-calculate the value arrays and pdf/cdf arrays and use those as interpolation tables during the sampling. This takes into account the dependency on other variables for each sampling variable.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

multiplicity_fraction_function

Description:

Which multiplicity fraction function to use. 0: None, 1: Arenou 2010, 2: Rhagavan 2010, 3: Moe and di Stefano (2017) 2017.

Default value:

0

Validation:

Any(<class ‘str’>, <class ‘int’>, msg=None)

n_logging_stats

Description:

Number of logging statistics used to calculate time remaining (etc.). E.g., if you set this to 10 the previous 10 calls to the verbose log will be used to construct an estimate of the time remaining.

Default value:

50

Validation:

<class ‘int’>

num_cores

Description:

The number of cores that the population grid will use. You can set this manually by entering an integer great than 0. When 0 uses all logical cores. When -1 uses all physical cores.

Default value:

1

Validation:

Any(<class ‘str’>, <class ‘int’>, <class ‘dict’>, msg=None)

original_command_line

Description:

The original command line command.

Default value:

None

Validation:

<class ‘str’>

original_submission_time

Description:

Sumission time of the script that invoked the Population code.

Default value:

None

Validation:

<class ‘str’>

original_working_directory

Description:

Original working directory of the script that invoked the population code.

Default value:

None

Validation:

<class ‘str’>

parse_function

Description:

Function that the user can provide to handle the output the binary_c. This function has to take the arguments (self, output). Its best not to return anything in this function, and just store stuff in the self.population_results dictionary, or just output results to a file.

Default value:

None

Validation:

<function callable_validation at 0x7f7a7d0a9dc0>

pre_evolve_function_hook

Description:

Function hook that gets used before the system is passed to binary_c. The function arguments should be (self, system_dict). If you return something from this function, the system_dict will be updated with that value.

Default value:

None

Validation:

<function callable_validation at 0x7f7a7d0a9dc0>

print_stack_on_exit

Description:

If True, prints a stack trace when the population’s exit method is called.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

repeat

Description:

Factor of how many times a system should be repeated. Consider the evolution splitting binary_c argument for supernovae kick repeating.

Default value:

1

Validation:

<class ‘int’>

restore_from_snapshot_dir

Description:

Directory that contains the snapshots.

Default value:

None

Validation:

<class ‘str’>

restore_from_snapshot_file

Description:

File of the snapshot to restore the population from.

Default value:

None

Validation:

<class ‘str’>

return_after_dry_run

Description:

If True, return immediately after a dry run (and don’t run actual stars). Default is False.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

run_zero_probability_system

Description:

Whether to run the zero probability systems.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

save_ensemble_chunks

Description:

Force the ensemble chunk to be saved even if we are joining a thread (just in case the joining fails).

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

save_population_object

Description:

Filename to which we should save a pickled grid object as the final thing we do.

Default value:

None

Validation:

<class ‘str’>

save_snapshot

Description:

TODO: not sure what the difference is with save_snapshots.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

save_snapshots

Description:

Flag whether to save snapshots of the population when terminated by a SIGINT.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

skip_before

Description:

The system number before which the systems are skipped.

Default value:

0

Validation:

<class ‘int’>

slurm

Description:

Flag used to control Slurm jobs. Default is 0 which means no Slurm. 1 means launch Slurm jobs. Do not manually set this to 2 (run Slurm jobs) or 3 (join Slurm job data) unless you know what you are doing, this is usually done for you.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

slurm_array

Description:

Override for Slurm’s –array option, useful for rerunning jobs manually.

Default value:

None

slurm_array_max_jobs

Description:

Override for the max number of concurrent Slurm array jobs.

Default value:

None

Validation:

<class ‘int’>

slurm_bash

Description:

Points the location of the “bash” command, e.g. /bin/bash, that is used in Slurm scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/bash

Validation:

<class ‘str’>

slurm_date

Description:

Points the location of the “date” command, e.g. /usr/bin/date, that is used in Slurm scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/date

Validation:

<class ‘str’>

slurm_dir

Description:

Working directory containing e.g. scripts, output, logs (e.g. should be NFS available to all jobs). This directory should not exist when you launch the Slurm jobs.

Default value:

Validation:

<class ‘str’>

slurm_env

Description:

Points the location of the “env” command, e.g. /usr/bin/env or /bin/env, that is used in Slurm scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/env

Validation:

<class ‘str’>

slurm_extra_settings

Description:

Dictionary of extra settings for Slurm to put in its launch script. Please see the Slurm documentation for the many options that are available to you.

Default value:

{}

Validation:

<class ‘dict’>

slurm_jobarrayindex

Description:

Slurm job array index. Each job is numbered <slurm_jobid>.<slurm_jobarrayindex>.

Default value:

None

slurm_jobid

Description:

Slurm job id. Each job is numbered <slurm_jobid>.<slurm_jobarrayindex>.

Default value:

slurm_jobname

Description:

Base names of the Slurm jobs, default “binary_c-python”.

Default value:

binary_c-python

Validation:

<class ‘str’>

slurm_memory

Description:

Memory required for the job. Should be in megabytes in a format that Slurm understands, e.g. “512MB” (the default).

Default value:

512MB

Validation:

<class ‘str’>

slurm_ntasks

Description:

Number of CPUs required per array job: usually only need this to be 1 (the default).

Default value:

1

Validation:

<class ‘int’>

slurm_partition

Description:

Slurm partition name. You should check your local Slurm installation to find out partition information, e.g. using the sview command.

Default value:

None

Validation:

<class ‘str’>

slurm_postpone_join

Description:

Flag to postpone the join of the job results. If activated then you have to do it later manually.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

slurm_postpone_sbatch

Description:

Flag to postpone launching the slurm jobs with sbatch. Just make the scripts that would have.

Default value:

0

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

slurm_pwd

Description:

Points the location of the “pwd” command, e.g. /bin/pwd, that is used in Slurm scripts. This is set automatically on the submit machine, so if it is different on the nodes, you should set it manually.

Default value:

/usr/bin/pwd

Validation:

<class ‘str’>

slurm_sbatch

Description:

The Slurm “sbatch” submission command, usually “/usr/bin/sbatch” but will depend on your Slurm installation. By default is set automatically.

Default value:

None

Validation:

<class ‘str’>

slurm_time

Description:

The time a Slurm job is allowed to take. Default is 0 which means no limit. Please check the Slurm documentation for required format of this option.

Default value:

0

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

slurm_warn_max_memory

Description:

If we set slurm_memory in excess of this, warn the user because this is usually a mistake. Default “1024MB”.

Default value:

1024MB

Validation:

<class ‘str’>

source_file_sampling_filename

Description:

Variable containing the source file containing lines of binary_c command line calls. These all have to start with binary_c.

Default value:

None

Validation:

<class ‘str’>

source_file_sampling_type

Description:

Type of formatting of the source-file sampling file contents. Allowed options: ‘commands’: formatted like the commandline command for binary_c, i.e. <key> <value> etc. ‘column’: column-based formatting. The first line of the file should contain the keys. The rest of the lines should contain the values in the correct columns.

Default value:

commands

Validation:

<class ‘str’>

start_at

Description:

The first system (number) that is allowed to run.

Default value:

0

Validation:

<class ‘int’>

start_time

Description:

Time the script that invoked the Population code started.

Default value:

05/31/2023 11:44:14

Validation:

<class ‘str’>

status_dir

Description:

Directory where grid status is stored.

Default value:

None

Validation:

<class ‘str’>

stop_queue

Description:

Flag whether to stop the queue.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

symlink_latest_gridcode

Description:

Symlink to latest gridcode.

Default value:

True

Validation:

<class ‘str’>

tmp_dir

Description:

Directory where certain types of output are stored. The grid code is stored in that directory, as well as the custom logging libraries. Log files and other diagnostics will usually be written to this location, unless specified otherwise.

Default value:

/tmp/binary_c_python-david

Validation:

<class ‘str’>

using_result_queue

Description:

Flag to enable using the result_queue that passes the results of binary_c (or those of the user-defined parse_function). This is a temporary parameter.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

verbosity

Description:

Verbosity of the population code. Default is 1, by which only errors will be handled by the logging object. Higher values will show more output. The verbosity levels correspond to the following logging levels: 0: CRITICAL, 1: ERROR, 2: WARNING, 3: INFO, 4: DEBUG.

Default value:

1

Validation:

<class ‘int’>

weight

Description:

Weight factor for each system. The calculated probability is multiplied by this. If the user wants each system to be repeated several times, then this variable should not be changed, rather change the _repeat variable instead, as that handles the reduction in probability per system. This is useful for systems that have a process with some random element in it.

Default value:

1.0

Validation:

<class ‘float’>

working_directory

Description:

Working directory of the script that invoked the population code.

Default value:

example path

Validation:

<class ‘str’>

Moe&diStefano distribution interpolation options

In this section we list the options that are available for the Moe&diStefano distribution interpolation. These are meant to be changed by the user.

Public options

Option

Description

IMF_distribution

Description:

IMF choice for the M&S sampling. Currently only supporting ‘kroupa2001’: Kroupa 2001 IMF and ‘chabrier2003’: Chabrier 2003 IMF.

Default value:

kroupa2001

JSON

Description:

Parameter that stores the interpolation data.

Default value:

None

Mmin

Description:

Minimum stellar mass that is regarded a star.

Default value:

0.08

multiplicity_model

Description:

Multiplicity model (as a function of log10M1)

You can use ‘Poisson’ which uses the system multiplicity given by Moe and maps this to single/binary/triple/quad fractions.

Alternatively, ‘data’ takes the fractions directly from the data, but then triples and quadruples are combined (and there are NO quadruples).

Default value:

Poisson

multiplicity_modulator

Description:

[single, binary, triple, quadruple]

e.g. [1,0,0,0] for single stars only

[0,1,0,0] for binary stars only

defaults to [1,1,0,0] i.e. singles and binaries.

Default value:

[1, 1, 0, 0]

normalize_multiplicities

Description:
‘norm’: normalise so the whole population is 1.0

after implementing the appropriate fractions S/(S+B+T+Q), B/(S+B+T+Q), T/(S+B+T+Q), Q/(S+B+T+Q) given a mix of multiplicities, you can either (noting that here (S,B,T,Q) = appropriate modulator * model(S,B,T,Q) ) note: if you only set one multiplicity_modulator to 1, and all the others to 0, then normalising will mean that you effectively have the same number of stars as single, binary, triple or quad (whichever is non-zero) i.e. the multiplicity fraction is ignored. This is probably not useful except for testing purposes or comparing to old grids.

‘raw’stick to what is predicted, i.e.

S/(S+B+T+Q), B/(S+B+T+Q), T/(S+B+T+Q), Q/(S+B+T+Q) without normalisation (in which case the total probability < 1.0 unless all you use single, binary, triple and quadruple)

‘merge’e.g. if you only have single and binary,

add the triples and quadruples to the binaries, so binaries represent all multiple systems … * this is canonical binary population synthesis *

It only takes the maximum multiplicity into account, i.e. it doesn’t multiply the resulting array by the multiplicity modulator again. This prevents the resulting array to always be 1 if only 1 multiplicity modulator element is nonzero

Note: if multiplicity_modulator == [1,1,1,1]. this option does nothing (equivalent to ‘raw’).

Default value:

merge

q_high_extrapolation_method

Description:

Same as q_low_extrapolation_method.

Default value:

flat

q_low_extrapolation_method

Description:
Q extrapolation (below 0.15) method

none flat linear2 plaw2 nolowq.

Default value:

flat

ranges

Description:

Ranges for the parameters that are sampled through the M&S distributions. Input is as follows: resolutions = {‘M’: [M1 lower bound, M2 upper bound], ‘q’: [q lower bound, q upper bound]}.

Default value:

{‘M’: [0.084, 80.0], ‘q’: [None, None], ‘logP’: [0.0, 8.0], ‘ecc’: [0.0, 0.99]}

resolutions

Description:

Dictionary that stores the resolutions for each of the variables that are used to sample the systems. The structure is as follows: resolutions = {‘M’: [M1 res, M2 res, ..], ‘logP’: [logP1 res, logP2 res, …], ‘ecc’: [ecc1 res, ecc2 res, …]}.

Default value:

{‘M’: [20, 20, 0, 0], ‘logP’: [20, 0, 0], ‘ecc’: [10, 0, 0]}

samplerfuncs

Description:

Sampler functions to each of the parameters. NEEDS UPDATING.

Default value:

{‘M’: [None, None, None, None], ‘logP’: [None, None, None], ‘ecc’: [None, None, None]}

Private internal variables

In this section we list the private internal parameters for the population code. These are not meant to be changed by the user.

Private internal variables

Option

Description

_Moe2017_JSON_data

Description:

Parameter to store the loaded Moe&diStefano2017 dataset.

Default value:

None

Validation:

<class ‘dict’>

_actually_evolve_system

Description:

Whether to actually evolve the systems of just act as if. for testing. used in _process_run_population_grid.

Default value:

True

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_binary_c_config_executable

Description:

Full path of the binary_c-config executable. This options is not used in the population object.

Default value:

example path

Validation:

<class ‘str’>

_binary_c_dir

Description:

Directory where binary_c is stored. This options are not really used.

Default value:

example path

Validation:

<class ‘str’>

_binary_c_executable

Description:

Full path to the binary_c executable. This options is not used in the population object.

Default value:

example path

Validation:

<class ‘str’>

_binary_c_shared_library

Description:

Full path to the libbinary_c file. This options is not used in the population object.

Default value:

example path

Validation:

<class ‘str’>

_commandline_input

Description:

String containing the arguments passed to the population object via the command line. Set and used by the population object.

Default value:

Validation:

<class ‘str’>

_count

Description:

Counter tracking which system the generator is on.

Default value:

0

Validation:

<class ‘int’>

_custom_logging_shared_library_file

Description:

Filename for the custom_logging shared library. Used and set by the population object.

Default value:

None

Validation:

<class ‘str’>

_end_time_evolution

Description:

Variable storing the end timestamp of the population evolution. Set by the object itself.

Default value:

0

Validation:

All(<class ‘float’>, <class ‘int’>, msg=None)

_errors_exceeded

Description:

Variable storing a Boolean flag whether the number of errors was higher than the set threshold (failed_systems_threshold). If True, then the command line arguments of the failing systems will not be stored in the failed_system_log files.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_errors_found

Description:

Variable storing a Boolean flag whether errors by binary_c are encountered.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_evolution_type_options

Description:

List containing the evolution type options.

Default value:

[‘grid’, ‘custom_generator’, ‘source_file’, ‘monte_carlo’]

Validation:

<class ‘list’>

_failed_count

Description:

Variable storing the number of failed systems.

Default value:

0

Validation:

<class ‘int’>

_failed_prob

Description:

Variable storing the total probability of all the failed systems.

Default value:

0

Validation:

<class ‘float’>

_failed_systems_error_codes

Description:

List storing the unique error codes raised by binary_c of the failed systems.

Default value:

[]

Validation:

<class ‘list’>

_killed

Description:

Parameter that stores whether the evolution was killed.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_loaded_Moe2017_data

Description:

Internal variable storing whether the Moe and di Stefano (2017) data has been loaded into memory.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_main_pid

Description:

Main process ID of the master process. Used and set by the population object.

Default value:

-1

Validation:

<class ‘int’>

_monte_carlo_current_total_count_evolved

Description:

Total number of systems evolved up until now.

Default value:

0

Validation:

<class ‘int’>

_monte_carlo_current_total_mass_evolved

Description:

Total mass evolved up until now.

Default value:

0

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

_monte_carlo_generator_filename

Description:

System generator filename.

Default value:

None

Validation:

<class ‘str’>

_monte_carlo_threshold_reached

Description:

Flag whether the threshold has been reached.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_num_processes

Description:

Number of processes launched by multiprocessing. This should be set automatically by binary_c-python, not by the user.

Default value:

1

Validation:

<class ‘int’>

_population_id

Description:

Unique 32-char hex string ID of the population.

Default value:

0

Validation:

<class ‘str’>

_probtot

Description:

Total probability of the population.

Default value:

0

Validation:

<class ‘float’>

_queue_done

Description:

Parameter that stores whether the queue is finished.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_sampling_variables

Description:

Dictionary storing the sampling_variables. These contain properties which are accessed by the _generate_grid_code function.

Default value:

{}

Validation:

<class ‘dict’>

_set_Moe2017_grid

Description:

Internal flag whether the Moe and di Stefano (2017) grid has been loaded.

Default value:

False

Validation:

All(Range(min=None, max=1, min_included=True, max_included=True, msg=None), <function Boolean at 0x7f7a7cfefe50>, msg=None)

_source_file_filehandle

Description:

Filehandle for the source file.

Default value:

None

Validation:

<class ‘str’>

_start_time_evolution

Description:

Variable storing the start timestamp of the population evolution. Set by the object itself.

Default value:

0

Validation:

All(<class ‘float’>, <class ‘int’>, msg=None)

_store_memaddr

Description:

Memory address of the store object for binary_c.

Default value:

-1

Validation:

Any(<class ‘int’>, <function capsule_validation at 0x7f7a7cfefd30>, msg=None)

_system_generator

Description:

Function object that contains the system generator function. This can be from a grid, or a source file, or a Monte Carlo grid.

Default value:

None

Validation:

<function iterator_validation at 0x7f7a7cfefdc0>

_total_mass_run

Description:

To count the total mass that thread/process has ran.

Default value:

0

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

_total_probability_weighted_mass_run

Description:

To count the total mass * probability for each system that thread/process has ran.

Default value:

0

Validation:

Any(<class ‘float’>, <class ‘int’>, msg=None)

_total_starcount

Description:

Variable storing the total number of systems in the generator. Used and set by the population object.

Default value:

0

Validation:

<class ‘int’>

_zero_prob_stars_skipped

Description:

Internal counter to track how many systems are skipped because they have 0 probability.

Default value:

0

Validation:

<class ‘int’>